home *** CD-ROM | disk | FTP | other *** search
/ Animations / Animations CD - Disc 2.iso / c / requeststring.doc < prev    next >
Text File  |  1992-12-15  |  6KB  |  149 lines
  1.  
  2.    RequestString version 1.02, December 15th 1992 by Nicolas Dade.
  3.  
  4. this program and the source are public domain.
  5.  
  6. this program lets you request a string from the user, similarly to
  7. the many Yes/No/Maybe requesters. It can be used from a CLI or from
  8. ARexx. If it is started from WorkBench it automatically goes into
  9. arexx mode, since the workbench does not supply a standard output
  10. to which to write the string. WB2.04 or higher, of course.
  11.  
  12. template:
  13.  
  14. RTITLE=TITLE/K, TEXT=BODY, STRING, OKTEXT=POSITIVE,
  15. CANCELTEXT=NEGATIVE, PUBSCREEN/K, TFONT/K, SFONT/K, BFONT/K,
  16. CENTERX/N/K, CENTERY/N/K, INSTALLAREXX/S
  17.  
  18. RTITLE or TITLE lets you specify the title of the requester.
  19. TEXT or BODY lets you specify text which appears in the requester. Seperate
  20.     lines with "*n", just like with the Echo command from a shell.
  21. STRING    lets you specify the initial contents of the string (the default
  22.     value, in other words).
  23. OKTEXT or POSITIVE lets you specify the text which appears in the OK
  24.     gadget. the default is "OK".
  25. CANCELTEXT or NEGATIVE lets you specify the text which appears in
  26.     the Cancel gadget. the default is "Cancel".
  27. PUBSCREEN lets you specify the name of the public screen in which the
  28.     requester should appear. the default is the workbench screen.
  29.     This screen MUST exist.
  30. TFONT    lets you specify the font in which the TEXT string should be
  31.     drawn. the format is "name.font/height"---i.e. "Times.font/13"
  32.     If the font cannot be found, the screen's font is used.
  33. SFONT    lets you specify the font in which the string gadget should
  34.     use. same format as for TFONT.
  35. BFONT    lets you specify the font in which the button gadgets should
  36.     use. same format as for TFONT.
  37. CENTERX lets you specify the x coordinate of the center of the requester
  38. CENTERY lets you specify the y coordinate of the center of the requester
  39.     the default position is centered in the whole screen (not the
  40.     visible portion).
  41. or
  42. INSTALLAREXX lets you place RequestString into arexx mode. Commands send
  43.     to the port named REQUESTSTRING will cause a requester to pop up.
  44.     The RC and RESULT variables will contain the return code and the
  45.     string (so be sure to say OPTIONS RESULTS before you do this, or
  46.     you wont be getting the string back). The format of the command
  47.     is identical to to the arguments used when starting RequestString
  48.     from the CLI.
  49.     When this option is given all other options are ignored.
  50.  
  51. If RequestString is started from workbench it acts as if it had been
  52. started from a CLI with the INSTALLAREXX option, so if you give it
  53. the tooltype DONOTWAIT and put it in your WBStartup drawer it will be
  54. installed each time you boot.
  55. If course you can also put a line like
  56.  
  57. run >nil: RequestString INSTALLAREXX
  58.  
  59. in s:User-Startup and achieve exactly the same thing.
  60.  
  61. To get rid of RequestString in arexx mode, send it a ctrl-c signal.
  62. (Use the Break command from a CLI)
  63.  
  64.  
  65.  
  66. Examples:
  67.  
  68. entering
  69.  
  70. RequestString RTITLE="Format blank disk" TEXT="I am going to format
  71. the disk in drive DF0:*n*nplease enter the name of the new disk"
  72. OKTEXT="Format" TFONT=Times.font/13 SFONT=Times.font/11
  73. BFONT=Times.font/13 STRING="Empty" CENTERX=0 CENTERY=0
  74.  
  75. in a CLI will open a window flushed to the upper left corner of the screen,
  76. looking like
  77.  
  78.     +-+-----------------------------------------+-+
  79.     | | Format blank disk                | |
  80.     +-+-----------------------------------------+-+
  81.     |                          |
  82.     | I am going to format the disk in drive DF0: |
  83.     |                          | <- blank line in TEXT
  84.     | please enter the name of the new disk       |
  85.     |                          |
  86.     | [_Empty___________________________________] |
  87.     |                          |
  88.     |  [Format]                [Cancel]  |
  89.     |                          |
  90.     +---------------------------------------------+
  91.  
  92. If the user presses return in the string gadget, or presses the OK
  93. button (which has been labeled "Format" in this example),
  94. RequestString outputs the string to its standard output, and exits
  95. normaly.
  96.  
  97. If the user presses the close-window or the Cancel button
  98. RequestString outputs nothing, and returns with return code WARN
  99. (5).
  100.  
  101. If some problem occurs which prevents RequestString from running, it
  102. returns with return code FAIL (20).
  103.  
  104.  
  105. and if you have already put RequestString in arexx mode, executing
  106. an arexx script like
  107.  
  108. /* Simple arexx script to get a line from the user via the RequestString program, and to print that line out */
  109. options results /* so that arexx asks RequestString for a result string, which is placed in the variable RESULT */
  110.     /* call RequestString */
  111. address REQUESTSTRING 'text="Please enter some text" string="some text"'
  112.     /* if everything went ok then print out what the user entered */
  113. if rc=0 then say 'You entered "'result'".'
  114.     /* if the user canceled then say so */
  115. if rc=5 then say 'You canceled the requester.'
  116.     /* if RequestString had some problems then say so */
  117. if rc=20 then say 'Something kept RequestString from running.'
  118.  
  119. will request some text from the user.
  120.  
  121.  
  122. If you require any sort of post-request processing of the entered
  123. text (checking that it makes sense, putting double-quotes around it,
  124. etc...) you really ought to be calling RequestString through its
  125. arexx interface instead of driving yourself nuts fighting
  126. limitations of dos scripts. That means you, KH2 :)
  127.  
  128.  ---------------------------------------------------------------------------
  129.  
  130. changes from 1.01 to 1.02
  131.  
  132. 1) Bug which showed up when a font was specified has been fixed.
  133.    Sorry KH2 --- there was a d1 that should have been a d0.
  134.  
  135. 2) Width of window is adjusted so that STRING text is always fully
  136.    visible. (well, unless the screen is not wide enough for that)
  137.  
  138. 3) The 3.0 software from C= contains two commands, RequestChoice and
  139.    RequestFile, which are in a similar league with RequestString.
  140.    They use BODY, TITLE, POSITIVE and NEGATIVE in place of my TEXT,
  141.    RTITLE, OKTEXT and CANCELTEXT, so I've changed the template so
  142.    that both my old names and the C= names will work.
  143.  
  144. 4) The TEXT or BODY now allows multiple lines. Just seperate them
  145.    with "*n", just like you do with the Echo command (and, for that
  146.    matter, just like you would with C='s RequestChoice command).
  147.  
  148.  
  149.